home *** CD-ROM | disk | FTP | other *** search
/ Amiga News 95 / Amiga News 95.iso / dpat / dpat05 / find / find.doc < prev    next >
Text File  |  1990-01-17  |  8KB  |  205 lines

  1. NAME
  2.            find (this doc for v3.9b)
  3.  
  4. SYNOPSIS
  5.            find -[acgsv] <root dir> <pattern>
  6.  
  7. FUNCTION
  8.            Searches a directory and its subdirectories for the pattern
  9.  
  10. INPUTS
  11.            -[acgsv]     Options (see below)
  12.            <root dir>   Any valid AmigaDos directory name
  13.            <pattern>    A (very) restricted regular expression
  14.  
  15. RESULTS
  16.            Displays the name(s) found on standard output, and maybe more
  17.            depending on the options invoked
  18.  
  19. KNOWN BUGS
  20.  
  21.            If the -g option is used, the Shell prompt function %S will not
  22.            be updated. This can be achieved by calling CD after find.
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                                 Find
  32.                                 ----
  33.  
  34. November, 21st 1989                                  Author: Cédric BEUST
  35.  
  36. * A few lines to describe how it works
  37. --------------------------------------
  38.  
  39.     In fact, I did my best so that my command does not need any documentation
  40. to be used. This is due to the fact that I bothered a lot
  41. when I tried to master the CLI for the first time since no documentation
  42. at all was available at this time (ugh! Looks like prehistoric age!). I DO
  43. THINK that any command should be self-explanatory. Commodore programmers,
  44. do you hear me?
  45.  
  46.     All right, I said what I had to, so let's come to it.
  47.  
  48.     The initial idea was to have a Unix-like find command on Amiga. This
  49. has never been supplied by Commodore and I have always wondered why.
  50. Recently, I decided that I had wondered enough and I started programming
  51. it. The result is far from having all the Unix' find possibilities, but
  52. though, it helped me a lot (anyway, Unix' one has a lot of features which
  53. nobody never uses. Commodore's ones as well).
  54.  
  55.      If you type 'find' with nothing at all, or with wrong parameters or
  56. with a '?', you'll get the following lines (approximately):
  57.  
  58.   Find (v3.9b) - Recursive search of files
  59.   Copyright Cédric BEUST - NICE (France)
  60.  
  61. Usage: find -[acgv] <source dir> <pattern>
  62.  
  63.     Options:
  64.  
  65.             -a:  Don't stop at first occurence
  66.             -c:  Don't ignore case
  67.             -g:  Change to directory found
  68.             -s:  Stop as soon as something is found
  69.             -v:  Display search steps
  70.  
  71.  Wildcards: ? (any character), # (none or several times) and * (anything)
  72.  To abort search, type CTRL-C
  73.  
  74.      Isn't all that self-explanatory? As a matter of fact, it is. But yet,
  75. I will add a few things.
  76.  
  77.  
  78. * Syntax
  79. --------
  80.  
  81.   - The options
  82.  
  83.       So far, there are five options:
  84.  
  85.       -a:
  86.          Means that when a file is found, find doesn't stop and keeps on
  87.          searching until it has searched all the directories. This is
  88.          useful if you know that the name you are searching might be found
  89.          in several directories. NOTE: this option is automatically set if
  90.          you use a pattern. The reason why I did this is simple: if you
  91.          use a pattern, then you can't tell whether the first name that
  92.          will appear is the one you are looking for or not. And you
  93.          wouldn't like the program to stop at this point, would you?
  94.       -c:
  95.          By default, find will ignore letter case, i.e.
  96.              find jh0: test
  97.          will either match 'test' (of course!), 'Test', 'TESt', and so on.
  98.          With the -c flag on, only 'test' will be found.
  99.       -g:
  100.          This feature is especially useful in scripts. It makes a CD to the
  101.          found directory. This allows to do something to the name found
  102.          after it has been found (for example,  deleting it). For instance,
  103.          using it with the -s flag could produce a little shell script that
  104.          might delete all the hated .fastdir throughout your hard disk.
  105.          Good idea, isn't it?
  106.       -v:
  107.          This is for your eye's pleasure! It merely displays the          
  108.          directories it is scanning with an indentation in order to get   
  109.          an idea of the hierarchy of the disk searched (and also to prove 
  110.          that it is well doing what you expect!).
  111.       -s:
  112.          This one forces find to stop after the      
  113.          first name found, bypassing what I said a few lines above. You   
  114.          will surely object that this option is redundant with the -a     
  115.          one, but I don't think so and I have a good reason for that.     
  116.          Suppose you want to write a script that deletes all the .fastdir 
  117.          on your hard disk (the idea is not mine but Cedric's. Yeah,
  118.          another one). You use a 'find -g jh0: .fastdir' and as soon as
  119.          it is found, you delete it and you loop. OK. But suppose you want  
  120.          to delete a pattern... For example, all the .bak. Then, you have   
  121.          to force find to stop after each occurence it gets. That's what     
  122.          the -s option does. On the opposite, suppose that by default,
  123.          find stops ALWAYS as soon as it finds something, and suppose
  124.          there is an option to force it to continue. Will you always think
  125.          to use this option when looking for a pattern? I don't think I
  126.          will. So I prefer this solution.
  127.  
  128.    - The source dir
  129.        No need to write long about that. Any device name will do, even     
  130.        an 'assign'ed one (jh0:, df0:, mydir:, jh2:lib, etc...). This will
  131.        be the root directory, and find will then scan all its directories
  132.        and subdirectories.
  133.  
  134.    - The pattern
  135.        It may be a simple name or a pattern. This pattern follows
  136.        AmigaDos' weird conventions about this: only # and ? are accepted
  137.        in this version (3.9 as I am writing) and not ()|. So far, I didn't
  138.        find it was a big lack although I might need users' opinion. In
  139.        earlier versions of find, the wildcards used to be ? and *, which I
  140.        find much more convenient, and I don't think the reason is just a
  141.        matter of type saving (* takes one less key than #?, had you
  142.        noticed?). Has anyone out there ever used the # character with
  143.        something else than '?'? So why bother with this notation? Anyway, I
  144.        decided to stick to it since I'd like my command to have its place
  145.        in any c: directory. Let's see a few examples of pattern matching:
  146.  
  147.           a?c   -->  abc acc adc...
  148.           a#bc  -->  ac abc abbc abbbc...
  149.           a#?.c -->  a.c asadf.c aer.c...
  150.  
  151.        You see? I'll stop with these examples but I'm quite confident that
  152.        my pattern matching routine will work correctly even in the worst
  153.        cases (believe me, I've tested it quite a bit!). Anyway, I found
  154.        out that I rarely use something else than the ones I just
  155.        described.
  156.  
  157. -- Addendum for v3.9b: the * wildcard has been added. The previous ones
  158.                        still remain.
  159.  
  160.   A CTRL-C may be used at any time to abort search. I bet you'll find this
  161. feature useful when find is entering the depths of your directory and it
  162. has already given you the name you were looking for!
  163.  
  164.  
  165. * One last thing
  166. ----------------
  167.  
  168.   And this one deserves a special chapter since it is not said in the help
  169. menu (nobody is perfect! But don't criticize or I'll add it in next
  170. versions): if ever find couldn't find any file matching the pattern, it
  171. will send a return code of 5 (it is a WARN code). This is useful in
  172. scripts to know when find is finished with its work: all you have to do is
  173. to include a 'IF WARN SKIP END ELSE...' and it will not loop forever.
  174.  
  175. ;-{
  176.   In the current version (3.9b), I still haven't figured out how to impose
  177. the new current directory to this #?!#@ %S prompt. It's really getting on my
  178. nerves.
  179.  
  180. :-)
  181.   Well! Looks like I wrote a bit more than what I thought. And yet, it is
  182. a soooo short command! There will be probably other versions, depending on
  183. the suggestions I am made (this is for YOU!). But I can already announce
  184. that there will probably be a Workbench version of this function (alike
  185. Mac's one). But this will take much more work to do.
  186.  
  187.   A few thanks to all the ones who helped me improve this command and add
  188. new options, and mainly: Cédric Nérot (for Guru proof thorough testing and
  189. the .fastdir application program), Jean-Charles Godien (special thanks to
  190. him! Nifty pattern matching routine, JC!), Pierre Ardichvili (sharp-witted
  191. suggestions) and Bruce Lepper (alpha, beta, gamma, ... and other-greek-
  192. letters versions tester despite him).
  193.  
  194.                         Enjoy!
  195.  
  196.  
  197. You can send me your suggestions to this address:
  198.  
  199.       BEUST  Cédric
  200.        "Prométhée"
  201. 80 Av. du Bois de Cythère
  202.        06000 NICE
  203.          FRANCE
  204.     Tél. 93 96 00 23
  205.